Prototype: instance scripts as dropped-in .csx - #2374

Draft, to judge the authoring format before committing to one. Nothing here is wired into the server yet.

Why not a data format

Instance content is not declarative. The vocabulary these instances have always used is thirteen triggers — OnDeath, OnTimeout, OnAreaEntry, OnLockerOpen, OnMapClean, OnFirstEnable … — and about twenty-six actions: SummonMonster, SpawnPortal, SetMonsterLockers, ChangePortalType, StartClock, RefreshRaidGoals, End.

That is an event tree. YAML or XML around it becomes an invented DSL with conditionals and sequencing — the GitHub-Actions problem — and neither gives any checking of the VNums and enums this codebase leans on.

Why .csx rather than Lua or JS

Sandboxing is the only axis where a scripting language wins, and it only matters if packs come from someone other than you. Against that, .csx gives type safety and IntelliSense over ~40 verbs, and — the part that decided it for me — scripts stay testable.

Worth knowing before reaching for Lua: MoonSharp, the library most people pick, last shipped in 2016. NLua is alive but needs per-platform native binaries; Jint is alive and pure-managed, and remains the right choice if untrusted content ever becomes a requirement. IInstanceRun is deliberately the only thing a script touches, so swapping engine is a binding change, not a redesign.

The startup objection, measured and removed

Roslyn scripting costs 1352 ms to warm up and ~85 ms per script after. Compiling ~114 instances at boot would be about eleven seconds for no benefit.

So scripts compile on first entry and are cached. Measured in CompilingIsPaidOnceThenCached: cold 63 ms, warm 0 ms. Invisible to the player who opens the door.

What is here

• IInstanceRun — the verbs. This is the actual design; the engine behind it is swappable.
• InstanceScript — a base so a script overrides only the triggers it uses, the way real definitions omit what they do not have.
• CsxInstanceScriptLoader — lazy, cached, and fails loudly at load with the compiler diagnostics rather than opening a door onto an empty room.
• instances/timespace-01.csx — a time-space in 47 lines: clock, three monsters behind a locker, portal unlocked on clear, boss, success.

Tests

Six, driving the dropped-in file against a recording run and asserting the exact sequence of calls — including that a broken script throws at load. This is the argument for csx: instance content is testable with the same harness as everything else, which for wave and timer logic is worth more than sandboxing.

Open questions

• The verb list is a representative subset, not all twenty-six. Widening it is mechanical once the shape is agreed.
• A script that loops forever would hang that map's life loop (perf: one awaited life loop per map instead of a 400ms timer per entity #2354). Trusted content makes that a bug rather than an attack, but the API should take a cancellation token.
• Overlaps feat(instances): time-space and raid entrances, from the capture to w… #2282, which parses the same content as XML. The half of that PR worth keeping either way is the entrance import, the wp/gp generation and the run lifecycle — none of which cares what format the definition came from.